home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD 2.1 / Amiga Developer CD v2.1.iso / NDK / NDK_3.5 / Documentation / Autodocs / nonvolatile.doc < prev    next >
Encoding:
Text File  |  1993-10-14  |  12.5 KB  |  361 lines
  1. TABLE OF CONTENTS
  2.  
  3. nonvolatile.library/--background--
  4. nonvolatile.library/DeleteNV
  5. nonvolatile.library/FreeNVData
  6. nonvolatile.library/GetCopyNV
  7. nonvolatile.library/GetNVInfo
  8. nonvolatile.library/GetNVList
  9. nonvolatile.library/SetNVProtection
  10. nonvolatile.library/StoreNV
  11. nonvolatile.library/--background--         nonvolatile.library/--background--
  12.  
  13.    PURPOSE
  14.     The nonvolatile library provides a simple means for an application
  15.     developer to manage nonvolatile storage.
  16.  
  17.    OVERVIEW
  18.     The nonvolatile library is meant to be used transparently across all
  19.     configurations. Currently, nonvolatile storage may consist of NVRAM
  20.     and/or disk devices. nonvolatile.library will automatically
  21.     access the best nonvolatile storage available in the system. Disk
  22.     based storage will be selected first and if not available, NVRAM
  23.     storage will be accessed.
  24.  
  25.     * NVRAM
  26.  
  27.     On low-end diskless Amiga platforms, NVRAM may be available. This
  28.     RAM will maintain its data contents when the system is powered down.
  29.     This is regardless of whether batteries or battery-backed clock are
  30.     present. The data stored in NVRAM is accessible only through the
  31.     ROM-based nonvolatile library funtion calls. The size of NVRAM
  32.     storage    is dependant on the system platform and is attainable through
  33.     the GetNVInfo() function.
  34.  
  35.     * Disk
  36.  
  37.     In keeping with the general configurability of the Amiga, the actual
  38.     disk location used by nonvolatile library when storing to disk may be
  39.     changed by the user.
  40.  
  41.     The prefs directory is used on the Amiga for storing many user
  42.     configurable options. The location for nonvolatile disk storage
  43.     is contained in the file prefs/env-archive/sys/nv_location. This
  44.     file should contain a data string that specifies a lockable location.
  45.     If the string does not specify a lockable location, the file will
  46.     be ignored.
  47.  
  48.     When opened, the nonvolatile library will search all drives within
  49.     the system until it finds this file and successfully accomplishes
  50.     a Lock on the location specified in the file. To force a rescan of
  51.     all drives, the library may be closed and reopened or execute the
  52.     GetNVInfo() function.
  53.  
  54.     A simple method for creating a floppy disk for saving nonvolatile
  55.     data is the following:
  56.  
  57.     Format a disk with the volume name NV
  58.     Create a file prefs/env-archive/sys/nv_location on this disk with
  59.       the following contents:  NV:nonvolatile
  60.     Create a directory nonvolatile
  61.  
  62.     The following is a script file that can be used to make a floppy
  63.     for use with nonvolatile library:
  64.  
  65.     .KEY DRIVE/A,DISK
  66.     .BRA {
  67.     .KET }
  68.     format Drive {DRIVE} Name {DISK$NV} noicons ffs
  69.     makedir {DRIVE}prefs
  70.     makedir {DRIVE}nonvolatile
  71.     makedir {DRIVE}prefs/env-archive
  72.     makedir {DRIVE}prefs/env-archive/sys
  73.     echo {DISK$NV}:nonvolatile >{DRIVE}prefs/env-archive/sys/nv_location
  74.  
  75.     !!!NOTE!!!
  76.  
  77.     Because NVRAM performs disk access, you must open and use its
  78.     functionality from a DOS process, not an EXEC task.  Normally
  79.     your CDGS application is invoked as a DOS process so this
  80.     requirement generally should cause you no concern.  You just
  81.     need to be aware of this requirement should you create an
  82.     EXEC task and try to invoke nonvolatile.library from that task.
  83.  
  84. nonvolatile.library/DeleteNV                     nonvolatile.library/DeleteNV
  85.  
  86.    NAME
  87.     DeleteNV -- remove an entry from nonvoltatile storage. (V40)
  88.  
  89.    SYNOPSIS
  90.     success = DeleteNV(appName, itemName, killRequesters);
  91.     D0           A0        A1          D1
  92.  
  93.     BOOL DeleteNV(STRPTR, STRPTR, BOOL);
  94.  
  95.    FUNCTION
  96.     Searches the nonvolatile storage for the indicated entry and removes
  97.     it.
  98.  
  99.     The strings appName and itemName may not contain the '/' or ':'
  100.     characters. It is recommended that these characters be blocked
  101.     from user input when requesting AppName and ItemName strings.
  102.  
  103.    INPUTS
  104.     appName - NULL terminated string identifing the application that
  105.           created the data. Maximum length is 31.
  106.     ItemName - NULL terminated string uniquely identifing the data
  107.            within the application. Maximum length is 31.
  108.     killRequesters - suppress system requesters flag. TRUE if all system
  109.              requesters are to be suppressed during this function.
  110.              FALSE if system requesters are allowed.
  111.  
  112.    RESULT
  113.     success - TRUE will be returned if the entry is found and deleted.
  114.           If the entry is not found, FALSE will be returned.
  115.  
  116. nonvolatile.library/FreeNVData                 nonvolatile.library/FreeNVData
  117.  
  118.    NAME
  119.     FreeNVData -- release the memory allocated by a function of this
  120.               library. (V40)
  121.  
  122.    SYNOPSIS
  123.     FreeNVData(data);
  124.            A0
  125.  
  126.     VOID FreeNVData(APTR);
  127.  
  128.    FUNCTION
  129.     Frees a block of memory that was allocated by any of the following:
  130.     GetCopyNV(), GetNVInfo(), GetNVList().
  131.  
  132.    INPUTS
  133.     data - pointer to the memory block to be freed. If passed NULL,
  134.            this function does nothing.
  135.  
  136.    SEE ALSO
  137.     GetCopyNV(), GetNVInfo(), GetNVList()
  138.  
  139. nonvolatile.library/GetCopyNV                   nonvolatile.library/GetCopyNV
  140.  
  141.    NAME
  142.     GetCopyNV -- return a copy of an item stored in nonvolatile storage.
  143.              (V40)
  144.  
  145.    SYNOPSIS
  146.     data = GetCopyNV(appName, itemName, killRequesters);
  147.     D0         A0      A1        D1
  148.  
  149.     APTR GetCopyNV(STRPTR, STRPTR, BOOL);
  150.  
  151.    FUNCTION
  152.     Searches the nonvolatile storage for the indicated appName and
  153.     itemName. A pointer to a copy of this data will be returned.
  154.  
  155.     The strings appName and itemName may not contain the '/' or ':'
  156.     characters. It is recommended that these characters be blocked
  157.     from user input when requesting appName and itemName strings.
  158.  
  159.    INPUTS
  160.     appName - NULL terminated string indicating the application name
  161.           to be found. Maximum length is 31.
  162.     itemName - NULL terminated string indicated the item within the
  163.            application to be found. Maximum length is 31.
  164.     killRequesters - Suppress system requesters flag. TRUE if all system
  165.              requesters are to be suppressed during this function.
  166.              FALSE if system requesters are allowed.
  167.  
  168.    RESULT
  169.     data - pointer to a copy of the data found in the nonvolatile storage
  170.            assocated with appName and itemName. NULL will be returned
  171.            if there is insufficient memory or the appName/itemName does
  172.            not exist.
  173.  
  174.    SEE ALSO
  175.     FreeNVData(), <libraries/nonvolatile.h>
  176.  
  177. nonvolatile.library/GetNVInfo                   nonvolatile.library/GetNVInfo
  178.  
  179.    NAME
  180.     GetNVInfo -- report information on the current nonvolatile storage.
  181.              (V40)
  182.  
  183.    SYNOPSIS
  184.     information = GetNVInfo(killRequesters);
  185.     D0            D1
  186.  
  187.     struct NVInfo *GetNVInfo(BOOL);
  188.  
  189.    FUNCTION
  190.     Finds the user's preferred nonvolatile device and reports information
  191.     about it.
  192.  
  193.    INPUTS
  194.     killRequesters - suppress system requesters flag. TRUE if all system
  195.              requesters are to be suppressed during this function.
  196.              FALSE if system requesters are allowed.
  197.  
  198.    RESULT
  199.     information - pointer to an NVInfo structure. This structure contains
  200.               information on the NV storage media with the largest
  201.               storage. The structure contains 2 longword fields:
  202.               nvi_MaxStorage and nvi_FreeStorage. Both values are
  203.               rounded down to the nearest ten. The nvi_MaxStorage
  204.               field is defined as the total amount of nonvolatile
  205.               storage available on this device. The nvi_FreeStorage is
  206.               defined as the amount of available space for NVDISK or
  207.               the amount of non-locked storage for NVRAM. For NVDISK,
  208.               the nvi_FreeStorage takes into account the amount of
  209.               overhead room required to store a new App/Item. This
  210.               amount is 3 blocks to allow room for storing a new Item
  211.               file and possibly a new App directory. For NVRAM, the
  212.               amount of overhead is 5 bytes. However, the amount of
  213.               room required to store a new NVRAM item depends on the
  214.               length of the App and Item names. Refer to StoreNV()
  215.               function for storage details.
  216.  
  217.               This function may return NULL in the case of failure.
  218.  
  219.    SEE ALSO
  220.     FreeNVData(), StoreNV(), <libraries/nonvolatile.h>
  221.  
  222. nonvolatile.library/GetNVList                   nonvolatile.library/GetNVList
  223.  
  224.    NAME
  225.     GetNVList -- return a list of the items stored in nonvolatile
  226.              storage. (V40)
  227.  
  228.    SYNOPSIS
  229.     list = GetNVList(appName, killRequesters);
  230.     D0         A0      D1
  231.  
  232.     struct MinList *GetNVList(STRPTR, BOOL);
  233.  
  234.    FUNCTION
  235.     Returns a pointer to an Exec list of nonvolatile Items associated
  236.     with the appName requested.
  237.  
  238.     The string appName may not contain the '/' or ':' characters.
  239.     It is recommended that these characters be blocked from user input
  240.     when requesting an appName string.
  241.  
  242.    INPUTS
  243.     appName - NULL terminated string indicating the application name
  244.           to be matched. Maximum length is 31.
  245.     killRequesters - Suppress system requesters flag. TRUE if all system
  246.              requesters are to be suppressed during this function.
  247.              FALSE if system requesters are allowed.
  248.  
  249.    RESULT
  250.     list - a pointer to an Exec MinList of NVEntries. A NULL will be
  251.            returned if there is insufficient memory. If there are no
  252.            entries in the nonvolatile storage for the AppName, an
  253.            empty list will be returned.
  254.  
  255.    NOTE
  256.     The protection field contains more bits than are required for
  257.     storing the delete protection status. These bits are reserved
  258.     for other system usage and may not be zero. When checking for
  259.     the delete status use either the field mask NVIF_DELETE, or the
  260.     bit definition NVIB_DELETE.
  261.  
  262.    SEE ALSO
  263.     FreeNVData(), SetNVProtection()
  264.  
  265. nonvolatile.library/SetNVProtection       nonvolatile.library/SetNVProtection
  266.  
  267.    NAME
  268.     SetNVProtection -- set the protection flags. (V40)
  269.  
  270.    SYNOPSIS
  271.     success = SetNVProtection(appName, itemName, mask, killRequesters);
  272.     D0              A0       A1         D2    D1
  273.  
  274.     BOOL SetNVProtection(STRPTR, STRPTR, LONG, BOOL);
  275.  
  276.    FUNCTION
  277.     Sets the protection attributes for an item currently in the
  278.     nonvolatile storage.
  279.  
  280.     Although 'mask' is LONG only the delete bit, NVEF_DELETE/NVEB_DELETE,
  281.     may be set. If any other bits are set this function will return
  282.     FALSE.
  283.  
  284.     The strings appName and itemName may not contain the '/' or ':'
  285.     characters. It is recommended that these characters be blocked
  286.     from user input when requesting AppName and ItemName strings.
  287.  
  288.    INPUTS
  289.     appName - NULL terminated string indicating the application name
  290.           to be matched. Maximum length is 31.
  291.     itemName - NULL terminated string indicated the item within the
  292.            application to be found. Maximum length is 31.
  293.     mask - the new protection mask. Only set the delete bit otherwise
  294.            this function WILL CRASH.
  295.     killRequesters - suppress system requesters flag. TRUE if all system
  296.              requesters are to be suppressed during this function.
  297.              FALSE if system requesters are allowed.
  298.  
  299.    RESULT
  300.     success - FALSE if the protection could not be change (ie the data
  301.           does not exist).
  302.  
  303.    SEE ALSO
  304.     GetNVList(), <libraries/nonvolatile.h>
  305.  
  306. nonvolatile.library/StoreNV                       nonvolatile.library/StoreNV
  307.  
  308.    NAME
  309.     StoreNV -- store data in nonvolatile storage. (V40)
  310.  
  311.    SYNOPSIS
  312.     error = StoreNV(appName, itemName, data, length, killRequesters);
  313.     D0        A0     A1       A2    D0     D1
  314.  
  315.     UWORD StoreNV(STRPTR, STRPTR, APTR, ULONG, BOOL);
  316.  
  317.    FUNCTION
  318.     Saves some data in nonvolatile storage. The data is tagged with
  319.     AppName and ItemName so it can be retrieved later. No single
  320.     item should be larger than one fourth of the maximum storage as
  321.     returned by GetNVInfo().
  322.  
  323.     There is no data compression associated with this function.
  324.  
  325.     The strings, AppName and ItemName, should be short, but descriptive.
  326.     They need to be short since the string is stored with the data and
  327.     the nonvolatile storage for a stand alone game system is limited.
  328.     The game system allows the user to selectively remove entries from
  329.     storage, so the string should be desriptive.
  330.  
  331.     The strings AppName and ItemName may not contain the '/' or ':'
  332.     characters. It is recommended that these characters be blocked
  333.     from user input when requesting AppName and ItemName strings.
  334.  
  335.    INPUTS
  336.     appName - NULL terminated string identifying the application
  337.           creating the data. Maximum length is 31.
  338.     itemName - NULL terminated string uniquely identifying the data
  339.            within the application. Maximum length is 31.
  340.     data - pointer to the memory block to be stored.
  341.     length - number of bytes to be stored in the units of tens of
  342.          bytes. For example, if you have 23 bytes to store length = 3;
  343.          147 byte then length = 15.
  344.     killRequesters - suppress system requesters flag. TRUE if all system
  345.              requesters are to be suppressed during this function.
  346.              FALSE if system requesters are allowed.
  347.  
  348.    RESULT
  349.     error - 0                means no error,
  350.             NVERR_BADNAME    error in AppName, or ItemName.
  351.             NVERR_WRITEPROT  Nonvolatile storage is read only.
  352.             NVERR_FAIL       Failure in writing data (nonvolatile storage
  353.                  full, or write protected).
  354.             NVERR_FATAL      Fatal error when accessing nonvolatile
  355.                  storage, possible loss of previously saved
  356.                  nonvolatile data.
  357.  
  358.    SEE ALSO
  359.     GetCopyNV(), GetNVInfo()
  360.  
  361.